---
title: Deploy your Astro Site to GitHub Pages
description: How to deploy your Astro site to the web using GitHub Pages.
type: deploy
i18nReady: true
---

You can use [GitHub Pages](https://pages.github.com/) to host an Astro website directly from a repository on [GitHub.com](https://github.com/).

## How to deploy

You can deploy an Astro site to GitHub Pages by using [GitHub Actions](https://github.com/features/actions) to automatically build and deploy your site. To do this, your source code must be hosted on GitHub.

Astro maintains the official `withastro/action` to deploy your project with very little configuration. Follow the instructions below to deploy your Astro site to GitHub pages, and see [the package README](https://github.com/withastro/action) if you need more information.

## Configure Astro for GitHub Pages

### Deploying to a `github.io` URL 

Set the [`site`](/en/reference/configuration-reference/#site) and [`base`](/en/reference/configuration-reference/#base) options in `astro.config.mjs`.
    
```js title="astro.config.mjs" ins={4-5}
import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://astronaut.github.io',
  base: 'my-repo',
})
```

#### `site`

The value for `site` must be one of the following:

- The following URL based on your username: `https://<username>.github.io`
- The random URL autogenerated for a [GitHub Organization's private page](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site): `https://<random-string>.pages.github.io/`


#### `base`

A value for `base` may be required so that Astro will treat your repository name (e.g. `/my-repo`) as the root of your website.

:::note
  Don't set a `base` parameter if:

- Your page is served from the root folder.
- Your repository is located at `https://github.com/<USERNAME>/<USERNAME>.github.io`.
:::

The value for `base` should be your repository’s name starting with a forward slash, for example `/my-blog`. This is so that Astro understands your website's root is `/my-repo`, rather than the default `/`.

:::caution
    When this value is configured, all of your internal page links must be prefixed with your `base` value:

```astro ins="/my-repo"
<a href="/my-repo/about">About</a>
```

See more about [configuring a `base` value](/en/reference/configuration-reference/#base)
:::

### Using GitHub pages with a custom domain

:::tip[Set up a custom domain]
You can set up a custom domain by adding the following `./public/CNAME` file to your project: 

```js title="public/CNAME"
sub.mydomain.com
```

This will deploy your site at your custom domain instead of `user.github.io`. Don't forget to also [configure DNS for your domain provider](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain).   
:::

To configure Astro for using GitHub pages with a custom domain, set your domain as the value for `site`. Do not set a value for `base`:

```js title="astro.config.mjs" ins={4}
import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://example.com',
})
```

## Configure a GitHub Action

1. Create a new file in your project at `.github/workflows/deploy.yml` and paste in the YAML below.

    ```yaml title="deploy.yml"
    name: Deploy to GitHub Pages

    on:
      # Trigger the workflow every time you push to the `main` branch
      # Using a different branch name? Replace `main` with your branch’s name
      push:
        branches: [ main ]
      # Allows you to run this workflow manually from the Actions tab on GitHub.
      workflow_dispatch:
      
    # Allow this job to clone the repo and create a page deployment
    permissions:
      contents: read
      pages: write
      id-token: write

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout your repository using git
            uses: actions/checkout@v4
          - name: Install, build, and upload your site
            uses: withastro/action@v2
            # with:
              # path: . # The root location of your Astro project inside the repository. (optional)
              # node-version: 20 # The specific version of Node that should be used to build your site. Defaults to 20. (optional)
              # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)

      deploy:
        needs: build
        runs-on: ubuntu-latest
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
        steps:
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v4
    ```

    :::note
    The astro action takes a few optional inputs. These can be provided by uncommenting the `with:` line and the input you want to use.
    :::
    
    :::caution
    The official Astro [action](https://github.com/withastro/action) scans for a lockfile to detect your preferred package manager (`npm`, `yarn`, `pnpm`, or `bun`). You should commit your package manager's automatically generated `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb` file to your repository.
    :::

2. On GitHub, go to your repository’s **Settings** tab and find the **Pages** section of the settings.

3. Choose **GitHub Actions** as the **Source** of your site.  

4. Commit the new workflow file and push it to GitHub.  

  
Your site should now be published! When you push changes to your Astro project’s repository, the GitHub Action will automatically deploy them for you.
